<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head>
<title>Impose A Limit On Heap Size</title>
<style type="text/css">
body {
    margin: auto;
    font-family: Verdana, sans-serif;
    padding: 8px 1%;
}

a { color: #044a64 }
a:visited { color: #734559 }

.logo { position:absolute; margin:3px; }
.tagline {
  float:right;
  text-align:right;
  font-style:italic;
  width:300px;
  margin:12px;
  margin-top:58px;
}

.toolbar {
  text-align: center;
  line-height: 1.6em;
  margin: 0;
  padding: 0px 8px;
}
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
.toolbar a:visited { color: white; }
.toolbar a:hover { color: #044a64; background: white; }

.content    { margin: 5%; }
.content dt { font-weight:bold; }
.content dd { margin-bottom: 25px; margin-left:20%; }
.content ul { padding:0px; padding-left: 15px; margin:0px; }

/* rounded corners */
.se  { background: url(../images/se.gif) 100% 100% no-repeat #044a64}
.sw  { background: url(../images/sw.gif) 0% 100% no-repeat }
.ne  { background: url(../images/ne.gif) 100% 0% no-repeat }
.nw  { background: url(../images/nw.gif) 0% 0% no-repeat }

/* Things for "fancyformat" documents start here. */
.fancy img+p {font-style:italic}
.fancy .codeblock i { color: darkblue; }
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
.fancy h2 { margin-left: 10px }
.fancy h3 { margin-left: 20px }
.fancy h4 { margin-left: 30px }
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
.fancy #toc a        { color: darkblue ; text-decoration: none }
.fancy .todo         { color: #AA3333 ; font-style : italic }
.fancy .todo:before  { content: 'TODO:' }
.fancy p.todo        { border: solid #AA3333 1px; padding: 1ex }
.fancy img { display:block; }
.fancy :link:hover, .fancy :visited:hover { background: wheat }
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
.fancy li p { margin: 1em 0 }
/* End of "fancyformat" specific rules. */

</style>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
  
</head>
<body>
<div><!-- container div to satisfy validator -->

<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
 border="0"></a>
<div><!-- IE hack to prevent disappearing logo--></div>
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>

<table width=100% style="clear:both"><tr><td>
  <div class="se"><div class="sw"><div class="ne"><div class="nw">
  <table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
  <td width=100%>
  <div class="toolbar">
    <a href="../about.html">About</a>
    <a href="../sitemap.html">Sitemap</a>
    <a href="../docs.html">Documentation</a>
    <a href="../download.html">Download</a>
    <a href="../copyright.html">License</a>
    <a href="../news.html">News</a>
    <a href="../support.html">Support</a>
  </div>
<script>
  gMsg = "Search SQLite Docs..."
  function entersearch() {
    var q = document.getElementById("q");
    if( q.value == gMsg ) { q.value = "" }
    q.style.color = "black"
    q.style.fontStyle = "normal"
  }
  function leavesearch() {
    var q = document.getElementById("q");
    if( q.value == "" ) { 
      q.value = gMsg
      q.style.color = "#044a64"
      q.style.fontStyle = "italic"
    }
  }
</script>
<td>
    <div style="padding:0 1em 0px 0;white-space:nowrap">
    <form name=f method="GET" action="http://www.sqlite.org/search">
      <input id=q name=q type=text
       onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
      <input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
    </form>
    </div>
  </table>
</div></div></div></div>
</td></tr></table>
<div class=startsearch></div>
  
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Impose A Limit On Heap Size</h2><blockquote><pre>sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
</pre></blockquote><p>
The sqlite3_soft_heap_limit64() interface sets and/or queries the
soft limit on the amount of heap memory that may be allocated by SQLite.
SQLite strives to keep heap memory utilization below the soft heap
limit by reducing the number of pages held in the page cache
as heap memory usages approaches the limit.
The soft heap limit is "soft" because even though SQLite strives to stay
below the limit, it will exceed the limit rather than generate
an <a href="../c3ref/c_abort.html">SQLITE_NOMEM</a> error.  In other words, the soft heap limit
is advisory only.</p>

<p>The return value from sqlite3_soft_heap_limit64() is the size of
the soft heap limit prior to the call.  If the argument N is negative
then no change is made to the soft heap limit.  Hence, the current
size of the soft heap limit can be determined by invoking
sqlite3_soft_heap_limit64() with a negative argument.</p>

<p>If the argument N is zero then the soft heap limit is disabled.</p>

<p>The soft heap limit is not enforced in the current implementation
if one or more of following conditions are true:</p>

<p><ul>
<li> The soft heap limit is set to zero.
<li> Memory accounting is disabled using a combination of the
<a href="../c3ref/config.html">sqlite3_config</a>(<a href="../c3ref/c_config_getmalloc.html">SQLITE_CONFIG_MEMSTATUS</a>,...) start-time option and
the <a href="../compile.html#default_memstatus">SQLITE_DEFAULT_MEMSTATUS</a> compile-time option.
<li> An alternative page cache implementation is specified using
<a href="../c3ref/config.html">sqlite3_config</a>(<a href="../c3ref/c_config_getmalloc.html">SQLITE_CONFIG_PCACHE</a>,...).
<li> The page cache allocates from its own memory pool supplied
by <a href="../c3ref/config.html">sqlite3_config</a>(<a href="../c3ref/c_config_getmalloc.html">SQLITE_CONFIG_PAGECACHE</a>,...) rather than
from the heap.
</ul></p>

<p>Beginning with SQLite version 3.7.3, the soft heap limit is enforced
regardless of whether or not the <a href="../compile.html#enable_memory_management">SQLITE_ENABLE_MEMORY_MANAGEMENT</a>
compile-time option is invoked.  With <a href="../compile.html#enable_memory_management">SQLITE_ENABLE_MEMORY_MANAGEMENT</a>,
the soft heap limit is enforced on every memory allocation.  Without
<a href="../compile.html#enable_memory_management">SQLITE_ENABLE_MEMORY_MANAGEMENT</a>, the soft heap limit is only enforced
when memory is allocated by the page cache.  Testing suggests that because
the page cache is the predominate memory user in SQLite, most
applications will achieve adequate soft heap limit enforcement without
the use of <a href="../compile.html#enable_memory_management">SQLITE_ENABLE_MEMORY_MANAGEMENT</a>.</p>

<p>The circumstances under which SQLite will enforce the soft heap limit may
changes in future releases of SQLite.
</p><p>See also lists of
  <a href="objlist.html">Objects</a>,
  <a href="constlist.html">Constants</a>, and
  <a href="funclist.html">Functions</a>.</p>
